docs/development/Building in Eclipse.md

   1 # Building in Eclipse
   2
   3 How to build, test & debug Cleanflight in Eclipse on Linux, Windows & MacOS.
   4
   5 ## Checklist
   6
   7 Use this checklist to make sure you didn't miss a step. Versions mandated below are current and correct as of January 2016.
   8
   9 - [ ] [Download and Install](http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html) the latest (currently 1.8) 64bit Oracle JDK [read more](#install-the-jdk)
  10 - [ ] [Download and Install](https://eclipse.org/downloads/packages/eclipse-ide-cc-developers/lunasr2) Eclipse Luna (4.4) 64bit CDT edition, **NB:** not Mars or Neon [read more](#install-eclipse)
  11 - [ ] [Download and Install](https://launchpad.net/gcc-arm-embedded/4.9/4.9-2015-q3-update) the GCC ARM Embedded toolchain 4.9-2015-q3-update [read more](#install-arm-toolchain)
  12  - [ ] *Windows platform only:* [Download and Install](https://github.com/gnuarmeclipse/windows-build-tools/releases) the latest GNU ARM Eclipse Windows Build Tools
  13  - [ ] *Windows platform only:* Download and Install either [Cygwin](http://cygwin.com/install.html) or [MinGW MSYS](http://sourceforge.net/projects/mingw/files/latest/download)
  14 - [ ] Optionally [Download and Install](https://github.com/gnuarmeclipse/openocd/releases) the latest GNU ARM Eclipse OpenOCD [read more](#install-openocd)
  15  - [ ] *Linux platform only:* [Configure UDEV](http://gnuarmeclipse.github.io/openocd/install/#udev) to recognise USB JTAG probes
  16  - [ ] *Windows platform only:* [Download and Install](http://www.st.com/web/en/catalog/tools/FM147/SC1887/PF260219) the ST-Link / ST-LinkV2 drivers. These drivers do work on Windows 10 even if not yet mentioned by ST.
  17 - [ ] Optionally [Download and Install](https://github.com/gnuarmeclipse/qemu/releases) the latest GNU ARM Eclipse QEMU [read more](#install-qemu)
  18 - [ ] Add a new update site to Eclipse named "GNU ARM Eclipse Plugins" with the URL "http://gnuarmeclipse.sourceforge.net/updates" and install all the features offered
  19 - [ ] Configure [the recommended workspace settings](http://gnuarmeclipse.github.io/eclipse/workspace/preferences/)
  20 - [ ] Checkout the cleanflight source code [read more](#checkout-cleanflight)
  21  - [ ] *Windows platform only:* Add the msys or cygwin bin directory to the project path
  22 - [ ] Build the code by going to *Project menu -> Build All* [read more](#build)
  23 - [ ] Run the tests by creating and running a make target named "test"
  24 - [ ] Configure debugging [read more](#configure-debugging)
  25
  26 ## Extended Notes
  27
  28 ### Install the JDK
  29
  30 The [minimum JDK version](http://gnuarmeclipse.github.io/plugins/install/#java) supported by GNU Arm Eclipse is 1.7 but the current latest, 1.8, is recommended instead. While Oracle JDK is the recommended version, [they do also support](http://gnuarmeclipse.github.io/plugins/install/#java) the OpenJDK.
  31
  32 ### Install Eclipse
  33
  34 Eclipse Luna v4.4 is the preferred version for GNU Arm Tools currently. The minimum Eclipse version is Kepler 4.3. The maximum is Mars 4.5 although it is not tested by GNU Arm Eclipse and some things are [known to be broken](http://gnuarmeclipse.github.io/plugins/install/#eclipse--cdt). Eclipse Neon is currently not released.
  35
  36 CDT v8.6.0, as shipped in the Eclipse Luna CDT download, is recommended. The minimum CDT version is 8.3.
  37
  38 The 64bit Eclipse is preferred but a 32bit Eclipse can be used; ensure you run it on a 32bit JDK.
  39
  40 ### Install ARM Toolchain
  41
  42 The minimum version is 4.8-2014-q2. The maximum, and currently recommended version, is 4_9-2015q3.
  43
  44 GNU ARM Tools recommends that you don't add the toolchain to your path environment variable. This means you can install multiple versions of the toolchain without conflict. If you'll install only one version, it can make life easier when working outside Eclipse to add it to your path.
  45
  46 Retain the default installation directories so that the GNU ARM Plugins can locate the toolchain.
  47
  48 ### Install OpenOCD
  49
  50 You should install OpenOCD If you will be debugging on real hardware, such as the STM32F3DISCOVERY dev board. It is not required to simply build Cleanflight or run the tests.
  51
  52 ### Install QEMU
  53
  54 No tests currently run on the QEMU emulator therefore this install is entirely optional. It is useful to test your installation, since you can compile and run a blinky demo.
  55
  56 ### Checkout Cleanflight
  57
  58 If you'll be submitting changes to cleanflight, [fork the repository](https://help.github.com/articles/fork-a-repo/) on GitHub and checkout your copy.
  59
  60 In Eclipse go to *File -> Import* choose *Git -> Projects from Git*
  61
  62 ![projects from git](assets/building-in-eclipse/checkout-cleanflight-001.PNG)
  63
  64 Choose *Clone URI*
  65
  66 ![clone uri](assets/building-in-eclipse/checkout-cleanflight-002.PNG)
  67
  68 Enter the URI https://github.com/cleanflight/cleanflight or if you've forked the repo, enter your URI instead. With a fork, you will need to specify your authentication details
  69
  70 ![enter uri](assets/building-in-eclipse/checkout-cleanflight-003.PNG)
  71
  72 On the branch selection dialog, de-select all branches and select only *master*
  73
  74 ![choose branches to clone](assets/building-in-eclipse/checkout-cleanflight-004.PNG)
  75
  76 Select the default destination directory
  77
  78 ![destination](assets/building-in-eclipse/checkout-cleanflight-005.PNG)
  79
  80 When the download completes, choose *Use the New Project wizard* and click Finish
  81
  82 ![finish](assets/building-in-eclipse/checkout-cleanflight-006.PNG)
  83
  84 Choose *C/C++ -> Makefile Project with Existing Code*
  85
  86 ![makefile project](assets/building-in-eclipse/checkout-cleanflight-007.PNG)
  87
  88 Enter cleanflight as the project name and browse to your home directory -> git -> cleanflight for the existing code location. Ensure the C (cleanflight) and C++ (tests) languages are checked. Choose the Cross ARM GCC toolchain for the Indexer Settings. Click finish.
  89
  90 ![finish checkout](assets/building-in-eclipse/checkout-cleanflight-008.PNG)
  91
  92 Set your build and debug targets by going to project properties -> C/C++ Build and choose the Behaviour tab. Replace "all" in the build box with "TARGET=xxx DEBUG=GDB" where xxx is your platform such as NAZE
  93
  94 ![build](assets/building-in-eclipse/checkout-cleanflight-012.PNG)
  95
  96 On Windows only, add msys or cygwin bin directory to the project's path by right clicking the project and choosing properties
  97
  98 ![properties](assets/building-in-eclipse/checkout-cleanflight-009.PNG)
  99
 100 Edit the path variable in *C/C++ Build -> Environment*
 101
 102 ![edit path](assets/building-in-eclipse/checkout-cleanflight-010.PNG)
 103
 104 Append the full path to the relevant bin dir
 105
 106 ![append bin dir](assets/building-in-eclipse/checkout-cleanflight-011.PNG)
 107
 108 ### Build
 109
 110 Choose project -> build all
 111
 112 ![build all](assets/building-in-eclipse/checkout-cleanflight-013.PNG)
 113
 114 ### Configure Debugging
 115
 116 Choose debug -> debug configurations
 117
 118 ![debug configurations](assets/building-in-eclipse/checkout-cleanflight-014.PNG)
 119
 120 Create a new OpenOCD configuration for the obj\main\cleanflight_XXX.elf application (this file is generated by the build step above)
 121
 122 ![debug configurations](assets/building-in-eclipse/checkout-cleanflight-015.PNG)
 123
 124 Add the appropriate openocd board configuration parameter for your dev platform
 125
 126 ![openocd target](assets/building-in-eclipse/checkout-cleanflight-016.PNG)
 127
 128 Add the target to your debug menu favourites
 129
 130 ![debug favs](assets/building-in-eclipse/checkout-cleanflight-017.PNG)
 131